PR Review: SQL: Auto union Iceberg and Redpanda topic (#575)

Files reviewed: 6 .adoc files (466 additions / 17 deletions)
Overall assessment: The cleanest of the SQL GA series. Already engineer-APPROVED. Two broken xrefs are sibling-PR dependencies; same missing What's New entry; no style issues to flag. Ready to land as soon as #571 and #574 do.

What this PR does

Adds Redpanda SQL's Iceberg-bridge query support on the rp-sql integration branch:

• modules/sql/pages/query-data/query-iceberg-topics.adoc (new, 123 lines) — how-to that explains the auto-provisioned storage/Iceberg/Redpanda-catalog chain, maps a topic as a SQL table, runs a query that spans live + Iceberg history, and covers schema-divergence rules.
• modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc (new, 210 lines) — reference for the new statement with full options (uri, warehouse, four auth types — none/OAuth2/basic/AWS SigV4, TLS settings) and five worked examples.
• modules/reference/pages/sql/sql-statements/alter-iceberg-catalog.adoc (new, 40 lines) — modify connection properties of an existing Iceberg catalog.
• modules/reference/pages/sql/sql-statements/drop-iceberg-catalog.adoc (new, 33 lines) — drop an Iceberg catalog, with the documented constraint that a linked Redpanda catalog must be detached or dropped first.
• modules/reference/pages/sql/sql-statements/create-redpanda-catalog.adoc (56+ / 16−) — adds the new USING CATALOG clause, the conditional pandaproxy_url option, and a fourth example showing the linked-catalog form.
• modules/ROOT/nav.adoc — wires the new pages into the nav tree.

Jira ticket alignment

Ticket: DOC-2006 — "Document feature auto union Iceberg and Redpanda topic" (extracted from branch name).

Status: The PR delivers everything the ticket implies — bridge-query how-to + the three new Iceberg catalog SQL statements + USING-CATALOG documentation on the existing Redpanda catalog page. Greketrotny's engineering review addressed the REFRESH semantics and drop-with-link constraint, both of which are now documented correctly. ✓

Critical issues (must fix)

1. Two broken xrefs to sibling-PR targets (verified missing on rp-sql):

   File:line	xref target	Provided by
   query-iceberg-topics.adoc:13	sql:query-data/query-streaming-topics.adoc[]	PR #574 (still OPEN)
   query-iceberg-topics.adoc:21	sql:get-started/deploy-sql-cluster.adoc[Enable Redpanda SQL]	PR #571 (still OPEN)
   query-iceberg-topics.adoc:116	sql:query-data/query-streaming-topics.adoc[Query streaming topics] (Next steps)	PR #574 (still OPEN)

   • Fix: Same as #571 and #574 — coordinate merge ordering so all sibling PRs land on rp-sql before rp-sql lands on main. These three xrefs will all resolve once #574 and #571 have merged.

2. Missing What's New entry. Third PR in the SQL GA series with no entry in modules/get-started/pages/whats-new-cloud.adoc. As I noted in #571 and #574, a single coordinated "Redpanda SQL: General availability" entry for the whole series would cover this PR alongside the get-started, streaming-query, and OIDC/access pages.

   • Fix: Add the announcement entry once before any of #571 / #574 / #575 / #580 lands.

Suggestions (should consider)

1. Filename collision with the existing manage:iceberg/query-iceberg-topics.adoc. Two pages now share the basename query-iceberg-topics.adoc:

   • modules/sql/pages/query-data/query-iceberg-topics.adoc (new, this PR) — nav label: "Query Iceberg-enabled Topics"
   • modules/manage/pages/iceberg/query-iceberg-topics.adoc (pre-existing) — nav label: "Query Iceberg Topics"

   They live in different modules and the display labels differ, so navigation isn't actually ambiguous to readers. But it's the kind of overlap that bites later (typo'd xref lands on the wrong page; future grep across query-iceberg-topics returns both). Worth confirming this is intentional and that the two scopes (Redpanda SQL vs. external query engines) are clearly distinct in each page's intro.

2. // TODO placeholder in query-iceberg-topics.adoc:102:

   // TODO: Verify with engineering whether there are workload patterns that
   // reliably trigger longer planning, and document them if so (qa-questions.md #22).
   

   • Suggested: Open a follow-up ticket and reference it here (e.g., // TODO(DOC-XXXX): ...) so the TODO has an issue trail rather than a freeform pointer to a private QA document.

Impact on other files

• modules/ROOT/nav.adoc ✓ — all four new pages added at lines 357 (how-to), 541 (alter), 545 (create), 549 (drop).
• modules/get-started/pages/whats-new-cloud.adoc ❌ — no SQL GA entry (Critical #2).
• Cross-page consistency: the new how-to refers to bridge queries planning a union internally; the create-redpanda-catalog reference and create-iceberg-catalog reference describe the same model from their respective directions; create-redpanda-catalog's new "linked catalog" example is consistent with the auto-provisioned ALTER REDPANDA CATALOG ... USING CATALOG shown in the how-to. No drift detected. ✓
• Cross-component xrefs verified inside this PR's content:
  • xref:reference:properties/cluster-properties.adoc#iceberg_catalog_type ✓
  • xref:manage:iceberg/rest-catalog/index.adoc ✓
  • xref:manage:iceberg/about-iceberg-topics.adoc ✓
  • xref:sql:connect-to-sql/index.adoc ✓
  • xref:reference:sql/sql-statements/create-storage.adoc ✓ (already on rp-sql)
  • All intra-PR xrefs (create/alter/drop/redpanda-catalog statements) ✓
  • Only the two sibling-PR xrefs above are unresolved.
• Pre-existing manage:iceberg/query-iceberg-topics.adoc is unchanged by this PR and still in nav at line 433 — no breakage there.

CodeRabbit findings worth considering

None. CodeRabbit's check passed with no actionable findings.

Outstanding review activity (not findings — just status)

• Greketrotny's APPROVED (May 14 and May 15, two approvals on file).
• His follow-up COMMENTED reviews (May 18, May 20) raised three specific points:
  • "REFRESH pertains to the schema/shape of the table only" → current diff at lines 93–95 reflects this precisely.
  • "User cannot drop an iceberg catalog when there is another Kafka catalog linking" → documented at drop-iceberg-catalog.adoc:7–8.
  • "Don't document [this behavior]" on create-redpanda-catalog → Kat replied "Removed", and the current diff is clean.
• Greketrotny's final comment on the how-to was "looks accurate". No outstanding engineer-blocking concerns.

What works well

• Engineering-validated content. Greketrotny iterated on the technical specifics and ended with "looks accurate". The REFRESH guidance, the drop-with-link constraint, and the catalog-provisioning chain were all verified by the implementer.
• "How the query catalogs are set up" section is genuinely useful — it shows the three SQL statements Cloud runs under the hood so administrators can reason about the setup without being asked to run them, and so debugging-via-DESCRIBE makes sense.
• "Handle schema differences" section documents a real edge case (Iceberg table holding columns the topic schema no longer has, and the resulting planning-time error) with the exact resolution.
• Comprehensive options tables in the new reference pages — covering all four auth types in CREATE ICEBERG CATALOG plus TLS settings, plus AWS-default-credential-chain behavior for SigV4.
• Examples per reference page demonstrate every distinct usage shape — none of the three example pages is a single-snippet page.
• Related statements cross-link table at the bottom of create-iceberg-catalog.adoc makes lateral navigation between catalog statements easy.
• Frontmatter compliance: description, :page-topic-type: (how-to / reference), learning objectives observable and measurable, personas (app_developer, data_engineer) correctly scoped to the query-side audience.
• No em dashes anywhere in the new content (clean compared to #574).
• All H2+ headings in sentence case; H1s in title case (or all-caps SQL keywords). ✓
• All code blocks have explicit [source,sql] language tags. Consistent with the SQL module's convention.
• CI fully green and the Netlify preview links cover the four new pages.

Final-pass review via /docs-team-standards:pr-review.

@kbatuigas Other than the dependencies on other PRs being merged, and the What's new update, this looks clean. Going to approve with the understanding that the other PRs will be merged, and What's new update.